1. 一句话解释
REST API 是一种基于 HTTP 协议的标准化接口风格，让不同系统（如独立站、ERP、广告平台）用统一的“请求—响应”方式交换数据，实现订单、库存、广告等信息的自动同步。
2. 生活化类比
想象你在一家餐厅点餐。菜单就是 API 文档，服务员就是 REST API，厨房是后端系统。你不需要知道厨房怎么做菜，只需按菜单上的编号（端点）和格式（请求方法）下单，服务员就会把结果端回来。REST API 就是跨境电商系统之间的“服务员”：独立站把订单“下单”给 ERP，ERP 把库存“端回”给独立站，广告平台把转化数据“端给”分析系统。
3. 核心概念/公式
REST 的核心是“资源 + 方法 + 表示”。每个资源用 URL 标识，用 HTTP 方法操作，用 JSON/XML 传输。
常用 HTTP 方法：
| 方法 | 含义 | 跨境电商示例 |
|---|---|---|
| GET | 读取资源 | 获取订单列表 `/orders` |
| POST | 创建资源 | 创建新订单 `/orders` |
| PUT | 全量更新 | 更新库存 `/inventory/123` |
| PATCH | 部分更新 | 修改订单地址 `/orders/123` |
| DELETE | 删除资源 | 取消订单 `/orders/123` |
状态码公式：
- 2xx = 成功（200 OK，201 Created）
- 4xx = 客户端错误（400 参数错，401 未授权，404 不存在）
- 5xx = 服务端错误（500 内部错误，503 服务不可用）
一个典型请求：
GET https://api.shop.com/v1/orders?status=paid&limit=100 Authorization: Bearer <token>
返回：
{
"data": [
{"id": "1001", "sku": "A-01", "qty": 2, "status": "paid"}
],
"total": 1
}
4. 与相关术语对比
| 术语 | 通信风格 | 数据格式 | 实时性 | 跨境电商典型用途 |
|---|---|---|---|---|
| REST API | 请求—响应，无状态 | JSON/XML | 轮询或 webhook | 订单拉取、库存同步 |
| GraphQL | 查询语言，按需取字段 | JSON | 请求—响应 | 复杂商品目录查询 |
| Webhook | 服务端主动推送 | JSON | 近实时 | 订单创建后立即通知 ERP |
| SOAP | XML 协议，严格规范 | XML | 请求—响应 | 传统 ERP 对接 |
| gRPC | 二进制 RPC | Protobuf | 流式/双向 | 内部微服务高性能通信 |
REST 胜在通用、易调试、生态成熟；Webhook 适合事件驱动；GraphQL 适合前端灵活取数。独立站对接通常“REST 拉取 + Webhook 推送”组合使用。
5. 应用场景（含数据/案例）
场景一：订单同步
独立站每 5 分钟调用 GET /orders?updated_after=... 拉取新订单。某卖家日均 3000 单，若人工处理每单 2 分钟，需 100 小时；REST API 自动同步后，ERP 在 1 分钟内完成全部订单入库，效率提升 99% 以上。
场景二：库存同步
多平台卖家在 Shopify、Amazon、eBay 同时销售。通过 PUT /inventory/{sku} 将中心仓库存实时写回各平台。某 3C 卖家 SKU 数 1200 个，库存同步延迟从 30 分钟降到 15 秒，超卖率从 2.3% 降至 0.1%。
场景三：广告数据回传
独立站将转化事件通过 POST /conversions 回传至广告平台。某 DTC 品牌回传后，Facebook 广告 ROAS 从 1.8 提升到 2.6，CPA 下降 28%。
场景四：物流轨迹
调用 GET /trackings/{tracking_no} 获取物流节点，自动触发“已发货”“已签收”邮件，客服工单减少 40%。
6. 常见误区
误区一：REST 就是 JSON。 REST 是架构风格，JSON 只是常见表示格式，也可用 XML。
误区二：REST API 一定实时。 REST 本身是请求—响应，实时性靠轮询频率或 Webhook 补充。
误区三：所有接口都叫 REST。 只支持 POST、URL 里带动词（如 /getOrder）的接口，通常只是“HTTP API”，不是严格 REST。
误区四：忽略限流。 多数平台限制如 2 请求/秒，超限返回 429。需做退避重试，否则同步中断。
误区五：不验签。 生产环境必须用 HTTPS + Token/签名，否则订单和库存数据可被篡改。
7. 相关术语
- Webhook：服务端主动推送事件，常与 REST 互补。
- OAuth 2.0：REST API 常用授权框架，获取 access token。
- Rate Limit：接口调用频率限制，如 1000 次/小时。
- Idempotency Key：幂等键，防止重复创建订单。
- JSON：最常用的数据交换格式。
- Endpoint：API 的具体访问地址，如 /v1/orders。
- ERP：企业资源计划系统，常通过 REST API 与独立站对接。
- Middleware：中间件，用于转换和路由 API 请求。
